openapi: 3.0.3
info:  
  title: "PSA Verification of Payee - version 1.0.8 - 20250324"
  version: "1.0.9"
  description: |
    Technical specification for the VoP Application Programming Interface
    
    FULL SPECIFICATION
    
    ************************
    FOR PSA VoP PARTICIPANTS
    ************************
    
    CHANGES SINCE 1.0.8
    
    Correct BICType pattern to comply with ISO\
    Add data type vopLimitCode to allow limitation of response codes when responding on behalf of PSA participant\
    Insert vopLimit within verificationData for use of vopLimitCode
    
    CHANGES SINCE 1.0.7
    
    Add second server URL and description to URL use cases\
    Add optional header 'X-Request-Account-Servicer-BIC' to both post /payee-verifications and /payee-bulk-verrifications for requests by PSA VoP Service Members\
    Add http 421 error possibility and description\
    Rework enum of messageCode to reflect possibilities and description\
    Rework examples of verificationOfPayeeError\
    Add missing requirement of requestingAgent in verificationOfPayeeRequest\
    Add description to requestingAgent of both post /payee-verifications and /payee-bulk-verrifications\
    Rework position of errors and connected examples
    
  contact:
    name: 'PSA Payment Services Austria'
    url: 'https://www.psa.at/'
    email: 'office@psa.at'
    x-team-info:
      department: 'Account Systems'
      colleagues: 'Alexandra Karrer, Hendrik Muus, Marinko Ostojić'
externalDocs:
  description: |
    Verification of Payee PSA API description based on
    
    Verification Of Payee Scheme Rulebook - EPC218-23
    
    Verification Of Payee Inter-PSP API Specification - EPC103-24
    
    EPC API Security Framework - EPC164-22
    
  url: 'https://www.europeanpaymentscouncil.eu/what-we-do/other-schemes/verification-payee'
servers:
- url: https://api.vop.psa.at/{BIC}/vop/v1
  description: For requests from requesters not being a PSA VoP member
    {BIC} needs being replaced by the BIC (11) of the PSA VoP member the VoP request is directed to
- url: https://api.vop.psa.at/PSSAATWWXXX/vop/v1
  description: For requests from requesters being a PSA VoP member
paths:
  /payee-verifications:
    description: |
      Financial institution's VoP request, that need to be answered within 3 seconds, allowing for an overall 5 seconds from customers input to output to customer
      
      Open to any SEPA financial institution
    post:
      operationId: postVerificationOfPayeeRequest
      parameters:
      - $ref: '#/components/parameters/requestResponseId'
      - $ref: '#/components/parameters/requestTimestamp'
      - $ref: '#/components/parameters/requestAccountServicerBic'
      - $ref: '#/components/parameters/responseNotTimeCritical'
      requestBody:
        $ref: '#/components/requestBodies/singleRequest'
      responses:
        '200':
          $ref: '#/components/responses/singleResponse'
        '400':
          $ref: '#/components/responses/errors'
        '401':
          $ref: '#/components/responses/errors'
        '403':
          $ref: '#/components/responses/errors'
        '404':
          $ref: '#/components/responses/errors'
        '409':
          $ref: '#/components/responses/errors'
        '421':
          $ref: '#/components/responses/errors'
        '500':
          $ref: '#/components/responses/errors'
  /payee-bulk-verifications:
    description: |
      Financial institution's bulk VoP request
      
      Open to PSA VoP service members only
      
    post:
      operationId: postBulkVerificationOfPayeeRequest
      parameters:
      - $ref: '#/components/parameters/requestResponseId'
      - $ref: '#/components/parameters/requestTimestamp'
      - $ref: '#/components/parameters/requestAccountServicerBic'
      requestBody:
        $ref: '#/components/requestBodies/bulkRequest'
      responses:
        '201':
          $ref: '#/components/responses/bulkPostResponse'
        '400':
          $ref: '#/components/responses/errors'
        '401':
          $ref: '#/components/responses/errors'
        '403':
          $ref: '#/components/responses/errors'
        '404':
          $ref: '#/components/responses/errors'
        '409':
          $ref: '#/components/responses/errors'
        '500':
          $ref: '#/components/responses/errors'
  /payee-bulk-verifications/{bulkId}:
    description: |
      Result of a financial institution's bulk VoP request
      
      Open to PSA VoP service members only
      
      As the channel is secured by the certificate of the requester, the information contained in certificate is used to judge whether data containing responses are availabl for the requester.
      
    get:
      operationId: getBulkVerificationOfPayeeRequest
      parameters:
      - $ref: '#/components/parameters/requestResponseId'
      - $ref: '#/components/parameters/requestTimestamp'
      - $ref: '#/components/parameters/bulkId'
      responses:
        '200':
          $ref: '#/components/responses/bulkGetResponse'
        '202':
          $ref: '#/components/responses/bulkGetImpossible'
        '400':
          $ref: '#/components/responses/errors'
        '401':
          $ref: '#/components/responses/errors'
        '403':
          $ref: '#/components/responses/errors'
        '404':
          $ref: '#/components/responses/errors'
        '409':
          $ref: '#/components/responses/errors'
        '422':
          $ref: '#/components/responses/errors'
        '500':
          $ref: '#/components/responses/errors'
  /payee-data:
    description: |
      Request of PSA VoP service to a financial institution being member that hasn't provided data to PSA, but using the matching facilities
      
      This request is called by PSA VoP service and response has to be provided by the financial institution being member that hasn't provided data to PSA, but using the matching facilities
      
    post:
      operationId: postVerificationOfPayeeDataRequest
      parameters:
      - $ref: '#/components/parameters/requestResponseId'
      - $ref: '#/components/parameters/requestTimestamp'
      - $ref: '#/components/parameters/originalRequestId'
      - $ref: '#/components/parameters/originalRequestTimestamp'
      - $ref: '#/components/parameters/originalRequesterBIC'
      requestBody:
        $ref: '#/components/requestBodies/dataRequest'
      responses:
        '200':
          $ref: '#/components/responses/dataPostResponse'
        '400':
          $ref: '#/components/responses/errors'
        '401':
          $ref: '#/components/responses/errors'
        '403':
          $ref: '#/components/responses/errors'
        '404':
          $ref: '#/components/responses/errors'
        '409':
          $ref: '#/components/responses/errors'
        '421':
          $ref: '#/components/responses/errors'
        '500':
          $ref: '#/components/responses/errors'
components:
  headers:
    originalRequestId:
      description: |
        The original's VoP Request Message reference number
      schema:
        $ref: '#/components/schemas/UUIDType'
    originalRequesterBIC:
      description: |
        The original's VoP Request Message requester's BIC
      schema:
        $ref: '#/components/schemas/BICType'
    originalRequestTimestamp:
      description: |
        The original's VoP Request Message timestamp
      schema:
        $ref: '#/components/schemas/dateTimeType'
    requestResponseId:
      description: |
        The Requester's reference number of the VoP Request Message
      required: true
      schema:
        $ref: '#/components/schemas/UUIDType'
    responseTimestamp:
      description: |
        The Requester's timestamp of the VoP Request Message
      schema:
        $ref: '#/components/schemas/dateTimeType'
      required: true
    singleId:
      description: |
        The single Id assigned by the requester to a single entry of a bulk verification request.
      schema:
        $ref: '#/components/schemas/max36Text'
  parameters:
    bulkId:
      description: |
        The bulk Id assigned by the RVM (Routing and/or Verification Mechanism) to a bulk verification request
      in: path
      required: true
      name: bulkId
      schema:
        $ref: '#/components/schemas/UUIDType'
    originalRequestId:
      description: |
        The Requester's reference number of the VoP Request Message forwarded by the RVM (Routing and/or Verification Mechanism)
      in: header
      required: true
      name: X-Original-Request-Id
      schema:
        $ref: '#/components/schemas/UUIDType'
    originalRequesterBIC:
      description: |
        The Requester's BIC of the VoP Request Message forwarded by the RVM (Routing and/or Verification Mechanism)
      in: header
      required: true
      name: X-Original-Requesters-BIC
      schema:
        $ref: '#/components/schemas/BICType'
    originalRequestTimestamp:
      description: |
        The Requester's timestamp of the VoP Request Message forwarded by the RVM (Routing and/or Verification Mechanism)
      in: header
      required: true
      name: X-Original-Request-Timestamp
      schema:
        $ref: '#/components/schemas/dateTimeType'
    responseNotTimeCritical:
      description: |
        Indicator, whether response is released from standard response time frame and may take longer. Allow other requests to be prioritised. Time frame for indicated requests is extended to 58 seconds.
      in: header
      required: false
      name: X-Request-NTC
      schema:
        type: boolean
        example: 'true'
    requestAccountServicerBic:
      description: |
        The BIC of the account servicing bank serviced by 'participantBIC' according EDS entry 'accountHoldingBIC' at EPC
        This BIC is used for internal processes for PSA VoP Service Members and mandatory if ASPSP request uses participants BIC in VoP request
      in: header
      required: false
      name: X-Request-Account-Servicer-BIC
      schema:
        $ref: '#/components/schemas/BICType'
    requestResponseId:
      description: |
        The Requester's reference number of the VoP Request Message
      in: header
      required: true
      name: X-Request-ID
      schema:
        $ref: '#/components/schemas/UUIDType'
    requestTimestamp:
      description: |
        The Requester's timestamp of the VoP Request Message
      in: header
      required: true
      name: X-Request-Timestamp
      schema:
        $ref: '#/components/schemas/dateTimeType'
    singleId:
      description: |
        The single Id assigned by the requester to a single entry of a bulk verification request.
      in: header
      required: false
      name: singleId
      schema:
        $ref: '#/components/schemas/max36Text'
  requestBodies:
    dataRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/verificationOfPayeeDataRequest'
      required: true
    bulkRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/bulkVerificationOfPayeeRequest'
      required: true
    singleRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/verificationOfPayeeRequest'
      required: true
  responses:
    bulkGetImpossible:
      description: |
        Status information on a bulk VoP Request Message
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestResponseId'
        X-Response-Timestamp:
          $ref: '#/components/headers/responseTimestamp'
      content:
        application/json:
           schema:
            $ref: '#/components/schemas/bulkVerificationOfPayeeSubmitStatusResponse'
    bulkGetResponse:
      description: |
        Verification codes and possible additional information on a bulk VoP Request Message
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestResponseId'
        X-Response-Timestamp:
          $ref: '#/components/headers/responseTimestamp'
      content:
        application/json:
           schema:
            $ref: '#/components/schemas/bulkVerificationOfPayeeRetrieveResponse'
    bulkPostResponse:
      description: |
        The bulkId assigned by the RVM (Routing and/or Verification Mechanism) and possible additional information
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestResponseId'
        X-Response-Timestamp:
          $ref: '#/components/headers/responseTimestamp'
      content:
        application/json:
           schema:
            $ref: '#/components/schemas/bulkVerificationOfPayeeSubmitResponse'
    dataPostResponse:
      description: |
        Data assigned by the Responder to be used for VoP processing by the RVM (Routing and/or Verification Mechanism)
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestResponseId'
        X-Response-Timestamp:
          $ref: '#/components/headers/responseTimestamp'
      content:
        application/json:
           schema:
            $ref: '#/components/schemas/verificationOfPayeeDataResponse'
    errors:
      description: |
        Error according descriptive content. May occur from outside application too.\
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestResponseId'
        X-Response-Timestamp:
          $ref: '#/components/headers/responseTimestamp'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/verificationOfPayeeError'
          examples:
            400:
              description: |
                Bad Request - malformed payload.
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400"
                code: "FORMAT_ERROR"
                title: "Malformed JSON"
                status: 400
                detail: "Request Body could not be parsed or otherwise recognised"
                instance: 
            400_b:
              description: |
                Bad Request - malformed payload.
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400"
                code: "TIMESTAMP_INVALID"
                title: "Timestamp not accepted"
                status: 400
                detail: "Diviation between timestamp and current time is out of accepted bounds"
                instance: 
            400_c:
              description: |
                Bad Request - malformed payload.
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400"
                code: "UNKNOWN_ERROR"
                title: "Unspecific error condition"
                status: 400
                detail: "Request Body could not be parsed or otherwise recognised"
                instance: 
            401:
              description: |
                Unauthorized - not correctly authenticated to perform the request, e.g. no certificate, not accepted certificate type, etc.\
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401"
                code: "CLIENT_INVALID"
                title: "Authorisation failed"
                status: 401
                detail: "No certificate or unfitting certificate type used"
                instance: 
            403:
              description: |
                Forbidden - authorisation issue, certificate not acceptable, e.g. certificate's NAN do not match BIC in request, etc.\

              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403"
                code: "CLIENT_INCONSISTENT"
                title: "NAN and BIC don't match"
                status: 403
                detail: "BIC derived from NAN of certificate doesn't match BIC in request"
                instance: 
            404:
              description: |
                Not Found - resource not existing, e.g. resource according path in request not existing.\
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404"
                code: "NOT_FOUND"
                title: "Cannot find the requested resource"
                status: 404
                detail: "Resource is missing or has never existed"
                instance: 
            409:
              description: |
                Conflict - header carry duplicate entry, i.e. request id already used.\
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409"
                code: "DUPLICATE"
                title: "RequestId already in use"
                status: 409
                detail: "The request identification is already in use and therefore cannot be accepted"
                instance: 
            421:
              description: |
                Misdirected Request - request was directed to wrong server, i.e. none of the BICs is service member.\
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/421"
                code: "MISDIRECTED_REQUEST"
                title: "Cannot provide information requested"
                status: 421
                detail: "Requester responder combination unsupported"
                instance: 
            422:
              description: |
                Unprocessable Content - content of request not fitting process requirements, e.g. inconsistent, contradicting or ambiguous.\
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422"
                code: "RESOURCE_NOT_FOUND"
                title: "Resource according Id not found"
                status: 422
                detail: "Transmitted resource Id not fount among available resource Ids"
                instance: 
            451:
              description: |
                Unavailable For Legal Reasons - owner of NAN not supported, e.g. missing agreement may lead to GDPR issues.\
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/451"
                code: "CLIENT_UNKNOWN"
                title: "NAN not registered"
                status: 451
                detail: "The NAN given in certificate is not listed in list of supported requester's NANs"
                instance: 
            500:
              description: |
                Internal Server Error - technical problem occurred in the application code or application server preventing request execution.
              value:
                type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500"
                code: "SERVER_ERROR"
                title: "Internal error occurred while processing request"
                status: 500
                detail: "Server reported an error during computing. Technical personal has been informed about this issue"
                instance: 
    singleResponse:
      description: |
        A verification code and possible additional information assigned by the Responder
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestResponseId'
        X-Response-Timestamp:
          $ref: '#/components/headers/responseTimestamp'
      content:
        application/json:
           schema:
            $ref: '#/components/schemas/verificationOfPayeeResponse'
  schemas:
    BICType: 
      description: |
        Business Identifier Code according ISO 9362. May identify financial institutions and other organisations.
      type: string
      pattern: '^[A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$'
      example: 'ABCDBEBBFIM'
    IBANType: 
      description: |
        InternationalBankAccountNumber according ISO 13616, as assigned by the responding PSP.
      type: string
      pattern: '^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$'
      example: 'AB121234567812345678901234'
    LEIType: 
      description: |
        Code LEI (Legal Entity Identifier) according ISO 17442.
      type: string
      pattern: '^[A-Z0-9]{18}[0-9]{2}$'
      example: '549300DTUYXVMJXZNY75'
    UUIDType:
      description: | 
        A UUID according RFC 4122 Version 4.
      type: string
      format: uuid
      pattern: '^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$'
      example: '9f45a3e5-aa49-43d6-9f1c-36ae3b5a295e'
    academicTitleType:
      description: | 
        Acquired academic title and title position relative to name
      type: object
      properties:
        title:
          $ref: '#/components/schemas/max35Text'
        position:
          enum: [before, after]
      required:
        - title
        - position
    accountType:
      description: |
        InternationalBankAccountNumber according ISO 13616, as assigned by the responding PSP.
      type: object
      properties:
        iban:
          $ref: '#/components/schemas/IBANType' 
      required:
        - iban
    addressType:
      description: | 
        Address information
      type: object
      properties:
        department:
          $ref: '#/components/schemas/max70Text'
        subDepartment:
          $ref: '#/components/schemas/max70Text'
        streetName:
          $ref: '#/components/schemas/max70Text'
        buildingNumber:
          $ref: '#/components/schemas/max16Text'
        buildingName:
          $ref: '#/components/schemas/max35Text'
        floor:
          $ref: '#/components/schemas/max70Text'
        postBox:
          $ref: '#/components/schemas/max16Text'
        room:
          $ref: '#/components/schemas/max70Text'
        postCode:
          $ref: '#/components/schemas/max16Text'
        townName:
          $ref: '#/components/schemas/max35Text'
        townLocationName:
          $ref: '#/components/schemas/max35Text'
        districtName:
          $ref: '#/components/schemas/max35Text'
        countrySubDevision:
          $ref: '#/components/schemas/max35Text'
        country:
          $ref: '#/components/schemas/countryCode'
      required:
        - townName
        - country
    agentType:
      description: |
        Financial Institution Identifier within clearing and/or settlement systems.
      type: object
      properties:
        financialInstitutionId:
          $ref: '#/components/schemas/financialInstitutionId'
      required:
        - financialInstitutionId
    birthType:
      description: | 
        Information on person's birth
      type: object
      properties:
        birthDay:
          $ref: '#/components/schemas/dateType'
        provinceOfBirth:
          $ref: '#/components/schemas/max35Text'
        cityOfBirth:
          $ref: '#/components/schemas/max35Text'
        countryOfBirth:
          $ref: '#/components/schemas/countryCode'
      required:
       - birthDay
       - cityOfBirth
       - countryOfBirth
    bulkSingleEntry:
      description: | 
        Single account data for verification process.
      type: object
      properties:
        singleId:
          $ref: '#/components/schemas/max36Text'
        party:
          $ref: '#/components/schemas/partyType'
        partyAccount: 
          $ref: '#/components/schemas/accountType'
        partyAgent: 
          $ref: '#/components/schemas/agentType'
        unstructuredRemittanceInformation:
          description: | 
            Additional information about AT-C001 sent by the Requester AT-C007, 
            Usage Rule: only one entry may be used.
          type: array
          items:
            $ref: '#/components/schemas/max140Text'
          maxItems: 1
      required:
        - singleId
        - party
        - partyAccount
        - partyAgent
    bulkSingleResult:
      description: | 
        Result of the single entry out of bulk verification process.
      oneOf:
        - $ref: '#/components/schemas/bulkVerificationOfName'
        - $ref: '#/components/schemas/bulkVerificationOfNameClose'
        - $ref: '#/components/schemas/bulkVerificationOfId'
    bulkVerificationOfId:
      description: |
        Defined codes for IBAN - Id verification.
      type: object
      properties:
        singleId:
          $ref: '#/components/schemas/max36Text'
        partyIdMatch:
          $ref: '#/components/schemas/partyIdMatchType'
      required:
        - singleId
        - partyIdMatch
    bulkVerificationOfName:
      description: |
        Defined codes for IBAN - Name verification (not including close match).
      type: object
      properties:
        singleId:
          $ref: '#/components/schemas/max36Text'
        partyNameMatch:
          $ref: '#/components/schemas/nameMatchType'
      required:
        - singleId
        - partyNameMatch
    bulkVerificationOfNameClose:
      description: |
        Defined code for IBAN - Name verification on close match together with proposed name.
      type: object
      properties:
        singleId:
          $ref: '#/components/schemas/max36Text'
        partyNameMatch:
          $ref: '#/components/schemas/nameMatchTypeClose'
        matchedName:
          $ref: '#/components/schemas/max140Text'
      required:
        - singleId
        - partyNameMatch
        - matchedName
        - partyAgent
    bulkVerificationOfPayeeRequest:
      description: | 
        Request for the verification of bulk data.
      type: object
      properties:
        requestingAgent: 
          description: |
            The BIC of the requester registered as 'participantBIC' in EDS of EPC. BIC of account servicing banks registered as 'accountHoldingBIC' in EDS of EPC cannot be used for requesting agent. Account servicing banks need to use 'participantBIC' to which they are registered
            In case of PSA VoP Members additional Header X-Request-Account-Servicer-BIC is used to qualify the account servicer
          allOf:
            - $ref: '#/components/schemas/agentType'
        requestersBulkReference: 
          $ref: '#/components/schemas/max36Text'
        payees:
          type: array
          items:
            $ref: '#/components/schemas/bulkSingleEntry'
      required:
        - requestingAgent
        - payees
    bulkVerificationOfPayeeRetrieveResponse:
      description: | 
        Result of the bulk verification process.
      type: object
      properties:
        requestersBulkReference: 
          $ref: '#/components/schemas/max36Text'
        payees:
          type: array
          items:
            $ref: '#/components/schemas/bulkSingleResult'
      required:
        - payees
    bulkVerificationOfPayeeSubmitResponse:
      description: | 
        The bulkId assigned by the RVM (Routing and/or Verification Mechanism) created on submission of bulk verification data.
      type: object
      properties:
        bulkId:
          $ref: '#/components/schemas/UUIDType'
        requestersBulkReference: 
          $ref: '#/components/schemas/max36Text'
        numOfSingleRequests:
          description: | 
            Counted number of single requests in submitted bulk
          type: integer
          pattern: '^[1-9]\d*$'
          example: '27'
      required:
        - bulkId
        - numOfSingleRequests
    bulkVerificationOfPayeeSubmitStatusResponse:
      description: | 
        Status of the bulk verification process.
      type: object
      properties:
        requestersBulkReference: 
          $ref: '#/components/schemas/max36Text'
        numOfSingleRequests:
          description: | 
            Counted number of single requests in submitted bulk
          type: integer
          pattern: '^[1-9]\d*$'
          example: '27'
        numOfSolvedSingleRequests:
          description: | 
            Counted number of single requests in submitted bulk already collected
          type: integer
          pattern: '^[1-9]\d*$'
          example: '27'
      required:
        - numOfSingleRequests
        - numOfSolvedSingleRequests
    countryCode:
      description: | 
        Two alpha country code according ISO 3166
      type: string
      pattern: '^[A-Z]{2}$'
      example: 'AT'
    dateTimeType:
      description: |
        Timestamp in ISO 8601 format, either UTC (YYYY-MM-DDThh:mm:ss.sssZ) or local time with UTC offset (YYYY-MM-DDThh:mm:ss.sss+/-hh:mm), milliseconds precision (observe truncation rules !).
      type: string
      format: date-time
      pattern: '^\d{4}(-\d{2}){2}T\d{2}(:\d{2}){2}(\.\d{0,2}[1-9])?(Z|([-+]\d{2}(:\d{2})?))$'
      example: '2024-12-12T12:12:12Z ; 2024-12-12T12:12:12.02Z ; 2024-12-12T12:12:10+02'
    dateType:
      description: |
        Date in ISO 8601 format, either UTC (YYYY-MM-DDZ) or local time with UTC offset (YYYY-MM-DD+/-hh:mm).
      type: string
      format: date-time
      pattern: '^\d{4}(-\d{2}){2}(Z|([-+]\d{2}(:\d{2})?))$'
      example: '2024-12-12Z'
    financialInstitutionId:
      description: |
        Financial Institution Identifier within clearing and/or settlement systems.
      type: object
      properties:
        bicfi:
          $ref: '#/components/schemas/BICType'
      required:
        - bicfi
    genderType:
      description: |
        Gender of person from documents used in KYC process
      type: string
      enum: [Male, Female, Other]
      example: 'Other'
    genericOrganisationId:
      description: | 
        An organisation identifier and an identifier type qualified by either ‘schemeNameCode’ or ‘schemeNameProprietary’ and optionally an identifier issuer information
      oneOf:
        - $ref: '#/components/schemas/organisationCodedId'
        - $ref: '#/components/schemas/organisationProprietaryId'
    genericPersonId:
      description: | 
        A person identifier and an identifier type qualified by either ‘schemeNameCode’ or ‘schemeNameProprietary’ and optionally an identifier issuer information
      type: object
      properties:
        identification:
          $ref: '#/components/schemas/max35Text'
        schemeName:
          oneOf:
          - $ref: '#/components/schemas/schemeCode'
          - $ref: '#/components/schemas/proprietaryName'
        issuer:
          $ref: '#/components/schemas/max35Text'
      required:
        - identification
    idAsLEI:
      description: |
        Legal Entity Identifier according ISO 17442.
      type: object
      properties:
        lei:
          $ref: '#/components/schemas/LEIType'
    idAsBIC:
      description: |
        Business Identifier Code according ISO 9362. May identify financial institutions and other organisations.
      type: object
      properties:
        anyBIC:
          $ref: '#/components/schemas/BICType'
    idAsOther:
      description: | 
        An organisation identifier and an identifier type qualified by either ‘schemeNameCode’ or ‘schemeNameProprietary’ and optionally an identifier issuer information. Although the structure is an array, only one identifier is allowed
      type: object
      properties:
        others:
          type: array
          items:
            $ref: '#/components/schemas/genericOrganisationId'
          maxItems: 1
    idType:
      description: | 
        Unique identification of an organisation, as assigned by an institution, using an identification scheme.
      type: object
      properties:
        organisationId:
          $ref: '#/components/schemas/organisationIdType'
      required:
        - organisationId
    max140Text:
      type: string
      minLength: 1
      maxLength: 140
    max16Text:
      type: string
      minLength: 1
      maxLength: 16
    max256Text:
      type: string
      minLength: 1
      maxLength: 256
    max35Text:
      type: string
      minLength: 1
      maxLength: 35
    max36Text:
      description: |
        preferably a UUID
      type: string
      pattern: '^[a-z0-9A-Z\-_\.]*$'
      minLength: 1
      maxLength: 36
    max500Text:
      type: string
      minLength: 1
      maxLength: 500
    max70Text:
      type: string
      minLength: 1
      maxLength: 70
    messageCode:
      description: | 
        Specifies the codes Error messages.
      type: string
      enum: [FORMAT_ERROR, TIMESTAMP_INVALID, UNKNOWN_ERROR, CLIENT_INVALID, CLIENT_INCONSISTENT, NOT_FOUND, DUPLICATE, MISDIRECTED_REQUEST, RESOURCE_NOT_FOUND, CLIENT_UNKNOWN, SERVER_ERROR]
      example: 'TIMESTAMP_INVALID'
    nameMatchType:
      description: | 
        Specifies the codes -in sequence- for Match, NoMatch and MatchNotApplicable.
      type: string
      enum: [MTCH, NMTC, NOAP]
      example: 'MTCH'
    nameMatchTypeClose:
      description: | 
        Specifies the code CloseMatch.
      type: string
      enum: [CMTC]
      example: 'CMTC'
    organisationCodedId:
      description: |
        Unique and unambiguous identification of an organisation according provided coded scheme within issuers space.
      type: object
      properties:
        identification:
          $ref: '#/components/schemas/max256Text'
        schemeNameCode:
          $ref: '#/components/schemas/organisationIdCode'
        issuer:
          $ref: '#/components/schemas/max35Text'
      required:
        - identification
        - schemeNameCode
    organisationIdCode:
      description: |
        Specifies the external organisation identification scheme name code (maximum 4 characters) as defined in an external list (iso20022.org).
      type: string
      enum: [BANK, CBID, CHID, CINC, COID, CUST, DUNS, EMPL, GS1G, SREN, SRET, TXID, BDID, BOID]
      example: 'BOID'
    organisationIdType:
      description: | 
        Unique identification of an organisation, as assigned by an institution, using an identification scheme.
      oneOf:
        - $ref: '#/components/schemas/idAsLEI'
        - $ref: '#/components/schemas/idAsBIC'
        - $ref: '#/components/schemas/idAsOther'
    organisationProprietaryId:
      description: |
        Unique and unambiguous identification of an organisation according provided proprietary scheme eventually within issuers space.
      type: object
      properties:
        identification:
          $ref: '#/components/schemas/max256Text'
        schemeNameProprietary:
          $ref: '#/components/schemas/max35Text'
        issuer:
          $ref: '#/components/schemas/max35Text'
      required:
        - identification
        - schemeNameProprietary
    organisationType:
      description: | 
        Structure to hold information about an organisation
      type: object
      properties:
        type:
          $ref: '#/components/schemas/max35Text'
        identification:
          $ref: '#/components/schemas/idType'
        names:
          type: array
          items:
            $ref: '#/components/schemas/max140Text'
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/max140Text'
        address:
          $ref: '#/components/schemas/addressType'
      required:
        - organisationNames
    partyAsId:
      description: | 
        A party is identified by an identifier.
      type: object
      properties:
        identification:
          $ref: '#/components/schemas/idType'
      required:
        - identification
    partyAsName:
      description: | 
        A party is identified by a name.
      type: object
      properties:
        name:
          $ref: '#/components/schemas/max140Text'
      required:
        - name
    partyData:
      description: | 
        Structure holding information about a party / parties associated with an account.
      type: object
      properties:
        person:
          type: array
          items:
            $ref: '#/components/schemas/personType'
        organisation:
          type: array
          items:
            $ref: '#/components/schemas/organisationType'
    partyIdMatchType:
      description: | 
        Specifies the codes -in sequence- for Match, NoMatch and MatchNotApplicable.
      type: string
      enum: [MTCH, NMTC, NOAP]  
      example: 'MTCH'
    partyType:
      description: | 
        A party is either identified by a name or by an identifier.
      oneOf:
        - $ref: '#/components/schemas/partyAsName'
        - $ref: '#/components/schemas/partyAsId'
    personType:
      description: | 
        Structure to hold information about a person
      type: object
      properties:
        additionalInformation:
          $ref: '#/components/schemas/titlesType'
        firstNames:
          type: array
          items:
            $ref: '#/components/schemas/max140Text'
        lastNames:
          type: array
          items:
            $ref: '#/components/schemas/max140Text'
        name:
          $ref: '#/components/schemas/max140Text'
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/max140Text'
        address:
          $ref: '#/components/schemas/addressType'
        birthName:
          $ref: '#/components/schemas/max140Text'
        officialGender:
          $ref: '#/components/schemas/genderType'
        dateAndPlaceOfBirth:
          $ref: '#/components/schemas/birthType'
        identification:
          type: array
          items:
            $ref: '#/components/schemas/genericPersonId'
    proprietaryName:
      description: | 
        Proprietary information about the kind and/or nature of a code
      type: object
      properties:
        proprietary:
          $ref: '#/components/schemas/max35Text'
      required:
        - proprietary
    schemeCode:
      description: |
        Coded information about the kind and/or nature of a code
      type: object
      properties:
        code:
          $ref: '#/components/schemas/schemeType'
      required:
        - code
    schemeType:
      description: |
        Codes for the kind and/or nature of a code
      type: string
      enum: [ARNU, CCPT, CUST, DRLC, EMPL, NIDN, POID, SOSE, TELE, TXID]
      example: 'CCPT'
    titlesType:
      description: | 
        Structure for titles and other not categorised information connected to a person
      type: object
      properties:
        salutation:
          $ref: '#/components/schemas/max35Text'
        academicTitles:
          type: array
          items:
            $ref: '#/components/schemas/academicTitleType'
        otherTitles:
          type: array
          items:
            $ref: '#/components/schemas/max35Text'
        knownNames:
          type: array
          items:
            $ref: '#/components/schemas/max35Text'
    verificationData:
      description: | 
        Data returned to apply matching algorithms on.
      type: object
      properties:
        partyAccount:
          $ref: '#/components/schemas/accountType'
        vopLimit:
          $ref: '#/components/schemas/vopLimitCode'
        accountSince:
          $ref: '#/components/schemas/dateType'
        associatedNamesAndIds:
          $ref: '#/components/schemas/partyData'
      required:
        - partyAccount
        - associatedNamesAndIds
    verificationDataError:
      description: |
        No data returnable.
      type: object
      properties:
        partyMatch:
          description: | 
            In case no data can or shall be returned
          type: string
          enum: [NOAP]
          example: 'NOAP'
      required:
        - partyMatch
    verificationOfId:
      description: |
        Defined codes for IBAN - Id verification.
      type: object
      properties:
        partyIdMatch:
          $ref: '#/components/schemas/partyIdMatchType'
      required:
        - partyIdMatch
    verificationOfName:
      description: |
        Defined codes for IBAN - Name verification (not including close match).
      type: object
      properties:
        partyNameMatch:
          $ref: '#/components/schemas/nameMatchType'
      required:
        - partyNameMatch
    verificationOfNameClose:
      description: |
        Defined code for IBAN - Name verification on close match together with proposed name.
      type: object
      properties:
        partyNameMatch:
          $ref: '#/components/schemas/nameMatchTypeClose'
        matchedName:
          $ref: '#/components/schemas/max140Text'
      required:
        - partyNameMatch
        - matchedName
        - partyAgent
    verificationOfPayeeDataRequest:
      description: | 
        Request for the data needed for verification process.
      type: object
      properties:
        partyAccount: 
          $ref: '#/components/schemas/accountType'
      required:
        - partyAccount
    verificationOfPayeeDataResponse:
      description: | 
        Result of the verification data request.
      oneOf:
        - $ref: '#/components/schemas/verificationData'
        - $ref: '#/components/schemas/verificationDataError'
    verificationOfPayeeError:
      description: |
        Provides information on an error occurred.
      type: object
      properties:
        type: 
          $ref: '#/components/schemas/max70Text'
        code:
          $ref: '#/components/schemas/messageCode'
        title:
          $ref: '#/components/schemas/max70Text'
        status:
          type: integer
          enum: [400,401,403,404,409,421,422,451,500]
        detail:
          $ref: '#/components/schemas/max500Text'
        instance:
          $ref: '#/components/schemas/max256Text'
      required:
        - type
        - code
    verificationOfPayeeRequest:
      description: | 
        Request for the verification process.
      type: object
      properties:
        party:
          $ref: '#/components/schemas/partyType'
        partyAccount: 
          $ref: '#/components/schemas/accountType'
        partyAgent: 
          $ref: '#/components/schemas/agentType'
        unstructuredRemittanceInformation:
          description: | 
            Additional information about AT-C001 sent by the Requester AT-C007. Although the structure is an array, only one item is allowed
          type: array
          items:
            $ref: '#/components/schemas/max140Text'
          maxItems: 1
        requestingAgent: 
          description: |
            The BIC of the requester registered as 'participantBIC' in EDS of EPC. BIC of account servicing banks registered as 'accountHoldingBIC' in EDS of EPC cannot be used for requesting agent. Account servicing banks need to use 'participantBIC' to which they are registered\
            In case of PSA VoP Members additional Header X-Request-Account-Servicer-BIC is used to qualify the account servicer
          allOf:
            - $ref: '#/components/schemas/agentType'
      required:
        - party
        - partyAccount
        - partyAgent
        - requestingAgent
    verificationOfPayeeResponse:
      description: | 
        Result of the verification process.
      oneOf:
        - $ref: '#/components/schemas/verificationOfName'
        - $ref: '#/components/schemas/verificationOfNameClose'
        - $ref: '#/components/schemas/verificationOfId'
    vopLimitCode:
      description: | 
        Determines the range of VoP response codes that shall be used in responses
      type: string
      enum: [NOAP, MONA, NOCM, FULL]
      example: 'FULL'